refactor(spec)!: retire the uncalled describeManagedApiMethodConflicts export - #33583

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 2 changed file(s) yielded no anchor (packages/spec/api-surface/data.json, packages/spec/export-origins/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 9a6fcdd25b080fdac8c640e5f03d04cbc8ade831 && git checkout 9a6fcdd25b080fdac8c640e5f03d04cbc8ade831
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4bba8b8f02fdbdf30e9ad41fc5d2a6fdd3ccaf2a 12a6f2e15dd70fc9a938eeb0dbb23214ad043b6c && git checkout -B drift-repro 4bba8b8f02fdbdf30e9ad41fc5d2a6fdd3ccaf2a && git merge --no-ff 12a6f2e15dd70fc9a938eeb0dbb23214ad043b6c

node scripts/docs-audit/affected-docs.mjs --json 4bba8b8f02fdbdf30e9ad41fc5d2a6fdd3ccaf2a

domain:spec#4 · os-project-manager · session_01FEkQ5mecqk8M5q9vjKj6aS

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 12a6f2e15dd70fc9a938eeb0dbb23214ad043b6c
Local-runs: none
Scope: packages/spec/src/data/managed-api-affordance.ts + none (no other file in the diff implements or enforces it; .changeset/33522-retire-describe-managed-api-method-conflicts.md is judged in ② for level, banner and ADR-0087 marker only; the test file and the two generated snapshots are the lane seat's ACCEPT, read here only to answer ①)

Inputs read: card #33522 body and all three comments (triage 6886170312, claim 6886195399, dev report 6887762168), PR #33583 body and file list (5 files), the net diff origin/main...12a6f2e1 (merge base 8e63ed87), and the 72 check-runs on the head: 57 success, 15 skipped, 0 failure, 0 pending (both Check Changeset runs completed success; Lint & Repo Gates, Lint · CI, release & engine gates, TypeScript Type Check, Type Check UI, Test Core 8/8, Test UI 16/16, Build Core, Governed Surface Queue Guard, Dogfood Regression Gate all success). Read outside the diff, not reviewed: scripts/check-adr-0087-registration.mjs and docs/adr/0087-metadata-protocol-upgrade-contract.md on main, AGENTS.md Post-Task Checklist step 3, packages/objectql/src/registry.ts, packages/lint/src/validate-managed-api-methods.ts, packages/spec/src/index.ts, packages/spec/src/data/index.ts.

① Derived judgments

• Public surface: one published runtime export removed from @objectstack/spec/data. Right, and declared as what it is (a narrowing). describeManagedApiMethodConflicts reached the package's public entries through exactly one path: packages/spec/src/data/index.ts:192 (export * from './managed-api-affordance'). The root entry packages/spec/src/index.ts exports no domain namespace (its header says so, and its only star exports are ./stack.zod and ./conversions/index.js); on main the name occurs in api-surface/data.json and export-origins/data.json and in no other snapshot (root.json and the 17 other subpath snapshots: 0 hits). So the removal is from the ./data subpath alone, as the changeset says.
• Nothing else reachable is lost. Right. The diff deletes one function and its docblock (22 lines) and no type, constant or re-export. ManagedApiMethodConflict (its parameter type), MANAGED_WRITE_VERB_AFFORDANCE and checkManagedApiMethodAffordances are still declared and still present in both snapshots at the head (export-origins/data.json lines 443, 450, 894). The function's return type was string; no named type existed only for it.
• Generated snapshots: exactly one removed name each. Right. api-surface/data.json loses the line describeManagedApiMethodConflicts (function); export-origins/data.json loses the one key mapping it to src/data/managed-api-affordance.ts. No other line moves in either file, and git grep at the head finds the name in no snapshot.
• Accept-set: unchanged. Right. No schema, no authorable key, no verdict moves. checkManagedApiMethodAffordances is byte-identical, so every finding of object/managed-api-method-unaffordable and every boot-time strip is what it was.
• Test surface: the removed function's own describe block (4 cases) and its import go; nothing else. Right. The remaining suites still use managed(), verbs() and the ManagedApiMethodConflict type import, so no orphan is left behind (Type Check · source gates and Lint · ESLint success on the head).

② Semver level

• Level patch on @objectstack/spec: right. AGENTS.md step 3: the level follows the Metadata-protocol: kind alone, none takes patch, and "a non-protocol change, widening or breaking, ships patch and keeps its BREAKING banner and ADR-0087 disposition". A removed runtime function is not something a metadata author can write.
• Metadata-protocol: none: right. No key, accepted value, metadata type, default or meaning changes. Line-initial in both the changeset body and the PR body.
• Clause-②: no (narrowing): right. The published surface shrinks by one export and no rule or schema clause is added; (narrowing) is the BREAKING arm and the body carries the **BREAKING** banner, the bang in the subject, and the consumer named (a TypeScript caller importing the name from @objectstack/spec/data). Line-initial in both bodies, and the two bodies agree.
• The caller's fix is in the body: sufficient. Step 3 asks a removed export to carry its FROM to TO mapping and one-line fix. The body states the compiler error (TS2305), the action (delete the import) and the replacement (word the message from each conflict's verb and needs). There is no TO symbol to map to; the sentence is the whole migration. It is written as prose, not a FROM/TO block, which is forced by the marker below.
• ADR-0087 marker not-required (no-migration-prescription): honest and sufficient on main today. Not a must-fix. Read against the gate source and the ADR on main:
  • runtime-export-retired is the category built for this class (ADR-0087 D9), and it is closed to this operand by the gate's own text: "A subpath entry (@scope/pkg/sub). Only the root entry is read; a retirement from a subpath names no operand this category can verify, so it is refused at the mapping step rather than assumed." The ADR's D9 says the same under "What this does not decide". With the root-package operand, predicate 1 retired-from-entry reads packages/spec/src/index.ts at the merge base and the name is not among its exports (confirmed in ① from root.json and the entry source), so the claim would be false, not merely unverifiable. Claiming it would be the dishonest marker.
  • The other fact-backed categories are closed on facts the tree confirms: the package publishes (unpublished false); the diff adds no ledger entry and none exists for a function (registered, already-registered); a function is neither an exported type declaration at HEAD nor a type narrowed off any (runtime-interface-only, type-surface-only).
  • no-migration-prescription has two refusals on main: a body carrying a prescription the detector reads, and a changeset declaring Metadata-protocol: narrowed. Neither applies: the kind is none (which the ADR says "keep[s] the exemption"), and the gate's check-run is green on this head. The category's substantive claim, that the ledger and objectstack migrate meta have nothing to rewrite, is true here; D8 names this exact case ("it simply cannot tell a prescription for a metadata upgrader from a prescription for a source-code consumer, and only the first is the ledger's business").
  • The marker's justification states the limitation in the open (the name lives on ./data, the category reads the root only). It is not held by a concealed detector miss: nothing in the body is an arrowless FROM/TO line of the kind D9 was written to stop.
• nit (N1, accepted deviation, no fix owed): the caller's fix is a sentence because this category refuses a FROM/TO block; the ideal shape is runtime-export-retired @objectstack/spec/data#describeManagedApiMethodConflicts with a FROM line, which only PR feat(adr-0087): runtime-export-retired reads literal subpath keys #33520's gate can verify. No effect on correctness or on what an upgrading consumer reads.

③ Boundary flags

• Open question (marker now vs. hold behind PR feat(adr-0087): runtime-export-retired reads literal subpath keys #33520): answered, option A. Land as is. feat(adr-0087): runtime-export-retired reads literal subpath keys #33520 is open, unmerged and awaiting its own tier's record; main's gate is the contract in force, and under it this marker is the one true disposition (②). Holding a p3 dead-surface removal behind a Tier H PR to swap one marker for another that says the same thing to the same reader buys nothing. After merge nothing is owed either: the ADR states a changeset already breaking at the branch point "is inherited and never re-judged", so feat(adr-0087): runtime-export-retired reads literal subpath keys #33520 landing later does not re-grade this one. If feat(adr-0087): runtime-export-retired reads literal subpath keys #33520 lands first, the swap is optional and is a changeset-only (prose face) edit; it moves the head, so it would need this record re-pointed. Not escalated.
• out_of_scope: packages/lint/CHANGELOG.md (two released entries) names "the spec's describeManagedApiMethodConflicts sentence". Answered: correct to leave. Release-owned (AGENTS.md: never edited in a code PR), and the sentence is history that is true of its release ("no longer appends ...").
• Reviewer-raised, outside this diff, no action here: the registry's boot warning (packages/objectql/src/registry.ts, reconcileManagedApiMethods) and the lint rule's message and hint still name userActions as the remedy on every bucket. That is the defect PR fix(objectql, lint): synced objects are told to drop write verbs, not to open userActions #33517 (card managedBy 'synced': the stripped-apiMethods warning and the lint sentence tell the author to open a verb through userActions, which a synced object refuses (after #32061) #32134) owns by ruling; this PR neither touches nor worsens it. The changeset's sentence that those two "each word their own message" is true as written and makes no claim that their wording is right on synced.
• Residual, stated by the dev and confirmed as stated: the cloud repository cannot be read from here and the org code search only covers what the token can see. A cloud import would fail at compile time (TS2305) on upgrade, never silently. Accepted under the claim's route ruling; not escalated.

④ Design judgment

packages/spec/src/data/managed-api-affordance.ts: the retirement holds. No must-fix, no should-fix.

• Zero consumers, re-verified at the head. git grep describeManagedApiMethodConflicts over the whole tree at 12a6f2e1 (including ui/, examples/, content/, docs/, skills/): the changeset (3 lines) and packages/lint/CHANGELOG.md (2 released entries, prose). No source, test, doc, skill or snapshot. On main the only additional hits are the definition, its own test and the two snapshots. /home/user/hotcrm and /home/user/gallery: 0 hits in the working tree and on origin/main. Org code search describeManagedApiMethodConflicts org:objectstack-ai: 4 hits, all in objectstack (definition, test, the two snapshots; the index still reflects main). A partial-name sweep (describeManagedApi) finds nothing a string-built or renamed reference could hide behind.
• Attempt to break it: a caller that relied on the sentence. The two production callers of the predicate build their own text and do not import the helper: reconcileManagedApiMethods (registry.ts) composes its warning from each conflict's verb, and validateManagedApiMethods composes message and hint from verb and needs. Removing the helper changes no string either emits. Test Core 8/8 and Test UI 16/16 are green with it gone.
• Attempt to break it: a comment left false. The only prose that said "the one sentence both consumers say" was the removed function's own docblock, and it leaves with the function. It was already false on main (neither consumer called it), so the removal makes the file truer, not staler. Every remaining comment was read against the tree: the file header's "exactly two consumers" describes the predicate and names reconcileManagedApiMethods and validateManagedApiMethods, both of which call checkManagedApiMethodAffordances at the head; "ONE table, read by the boot-time strip and by the authoring-time gate" is true; the docblocks of MANAGED_WRITE_VERB_AFFORDANCE, ManagedApiMethodConflict and checkManagedApiMethodAffordances name nothing removed. In the callers, registry.ts ("The judgement itself is NOT here ...") and the header of validate-managed-api-methods.ts ("All judgement lives in the SHARED predicate") speak of the predicate only; neither claims a shared sentence. The test file's header ("These cases mirror reconcileManagedApiMethods's own suite") stays true of what remains.
• Attempt to break it: the alternative route. The card offered "align" only if a consumer exists. None does, and the helper cannot be made true without widening its signature: ManagedApiMethodConflict carries verb, needs, index and no bucket, so it cannot know a synced object refuses the userActions remedy (ADR-0153 D4; object.zod.ts line 4598). Keeping a published sentence that is wrong on one bucket and read by nobody is the worse of the two outcomes; retire is the right route, and it matches the claim's ruling.
• Changeset prose against the tree. Each factual sentence checks: the subpath, the absence of callers, the two consumers wording their own messages, the three symbols that stay, the synced refusal. No overclaim found.

Findings: N1 (nit, ②, accepted deviation). No must-fix, no should-fix; nits alone end the round.

Implemented-by: claude/project-thread-8c9p9x
Reviewed-by: session_01FEkQ5mecqk8M5q9vjKj6aS

VERDICT: PASS

domain:spec#4 · os-project-manager · session_01FEkQ5mecqk8M5q9vjKj6aS

ACCEPT · PR #33583 (#33522) · head 12a6f2e15dd70fc9a938eeb0dbb23214ad043b6c · 2026-11-15T02:18Z

席位核对

• 形态: 5 files, +16/−55 (read from the PR's file list): describeManagedApiMethodConflicts and its docblock removed from packages/spec/src/data/managed-api-affordance.ts, its four test cases removed, one line out of each of api-surface/data.json and export-origins/data.json, and a '@objectstack/spec': patch changeset with the BREAKING banner. No governed path (check-governed-merges --pr 33583: NOT governed, 71 lines): Tier S.
• 前提实测: zero consumers, measured by the seat before dispatch (objectstack incl. ui/, hotcrm, gallery, org code search), re-measured by the dev on its base and by the reviewer at the head. checkManagedApiMethodAffordances, ManagedApiMethodConflict and MANAGED_WRITE_VERB_AFFORDANCE stay; both production callers word their own messages.
• 门禁 check-runs: on this head 72 runs: 57 success, 15 skipped, 0 failed. mergeable_state: clean.
• 契约复审: CONTRACT_REVIEW_TIER PASS on this head, record 6887825608 (one nit, accepted). Ruling-ref for the in-seat review: 「你有 fable ，车道契约复审可以自己做」.
• 接受的偏差: ADR-0087 marker not-required (no-migration-prescription), with the caller's fix as prose, because runtime-export-retired on main reads only the root entry and this name lives on ./data; the review judged it honest on main today (nit N1). Seat answer to the dev's open question: option A, land as is; no swap owed if PR feat(adr-0087): runtime-export-retired reads literal subpath keys #33520 lands later. Residual: the cloud repo is unreadable from this seat; an importer there fails loudly at compile time (TS2305).
• 范围外去向: two released packages/lint/CHANGELOG.md entries name the helper → dropped — release-owned history, true of its release. The userActions remedy wording in the registry warning and the lint rule is PR fix(objectql, lint): synced objects are told to drop write verbs, not to open userActions #33517's (managedBy 'synced': the stripped-apiMethods warning and the lint sentence tell the author to open a verb through userActions, which a synced object refuses (after #32061) #32134) by ruling.
• 落地条款: ready + auto-merge now under the maintainer's standing order 「按照 pm-dispatch 规则复核过的都授权」 (2026-10-25T11:35Z) and 「你应该使用 pm-dispatch 技能审核和落地pr」 (2026-11-07T16:59Z). K = 13 commits on main past the branch's last main merge 8e63ed87 (< 15).